How-To: Update a Lighthouse Node

Adrian Manning | Estimated read time: 8 min

How to Update Your Lighthouse Node

Introduction

This is a straightforward guide to updating your Lighthouse node to a new version. We highly recommend keeping your Lighthouse node up-to-date with latest releases as they provide security, performance and feature improvements.

The guides here explain how to download a released binary for your platform. If you prefer to build your Lighthouse binary from source, you can follow the Building from source instructions which will build a Lighthouse binary and store it in the ~/.cargo/bin/ directory.

There are a number of ways to upgrade a Lighthouse node depending on your set up. This article provides update information for the following set-ups:

  • Systemd - Use this guide if you followed Somer Esat's Guide to Staking on Ethereum 2 or you are using Lighthouse as a systemd service. (i.e you run systemctl start/stop <LighthouseService> to start/stop your Lighthouse node).
  • Docker - Use this guide if you are running Lighthouse within docker. (i.e use the commands docker start/stop <LighthouseService>).
  • Binary - Use this guide if you are running Lighthouse as a straight binary (i.e run lighthouse bn ... to start the Lighthouse client).

Systemd Upgrade Guide

If you have followed Somer Esat's Guide to Staking on Ethereum 2, he has included (in Appendix B) a guide for upgrading your Lighthouse node. If you have followed that guide, we recommend following Appendix B as the method described here is slightly more general.

The first step is to download the latest version of the Lighthouse client. The releases are built for a number of architectures as explained in the pre-built binaries section of the Lighthouse book.

For this example, we are going to use the x86_64-unknown-linux-gnu (most desktops/laptops) binary type and the version 2.0.1 of Lighthouse. (You can check the latest version of Lighthouse on the github repository, or use the automatic download script provided below).

To download the binary, replace version number and binary type you wish to download (in the first two lines respectively) and run:

export LH_VERSION=v2.0.1
export LH_BINARY_TYPE=x86_64-unknown-linux-gnu
curl -LO https://github.com/sigp/lighthouse/releases/download/$LH_VERSION/lighthouse-$LH_VERSION-$LH_BINARY_TYPE.tar.gz
curl -LO https://github.com/sigp/lighthouse/releases/download/$LH_VERSION/lighthouse-$LH_VERSION-$LH_BINARY_TYPE.tar.gz.asc
tar xvf lighthouse-$LH_VERSION-$LH_BINARY_TYPE.tar.gz

or you can download the latest version (replacing the binary type if needed) with the following:

export LH_BINARY_TYPE=x86_64-unknown-linux-gnu
export LH_VERSION=$(curl --silent "https://api.github.com/repos/sigp/lighthouse/releases/latest" |grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/')
curl -LO https://github.com/sigp/lighthouse/releases/download/$LH_VERSION/lighthouse-$LH_VERSION-$LH_BINARY_TYPE.tar.gz
curl -LO https://github.com/sigp/lighthouse/releases/download/$LH_VERSION/lighthouse-$LH_VERSION-$LH_BINARY_TYPE.tar.gz.asc
tar xvf lighthouse-$LH_VERSION-$LH_BINARY_TYPE.tar.gz

At this point, you should verify the signature of the downloaded data to ensure it was built by Sigma Prime.

You should now have a lighthouse binary in your current working directory.

To check its version and build-type run:

./lighthouse --version

Which will output the version in the following format:

Lighthouse v2.0.1-fff01b2
BLS library: blst-modern
SHA256 hardware acceleration: true
Specs: mainnet (true), minimal (false)

We now need to install the correct and verified binary to the system. This can done via:

sudo cp lighthouse /usr/bin

NOTE: Somer Esat's guide installs it to /usr/local/bin. You can install to this path if there are conflicts (or if you prefer).

Double check the version has updated via:

lighthouse --version

Now it's time to restart the Lighthouse beacon node and validator client (if you are running one).

Restart the processes via:

sudo systemctl restart lighthouse-bn
sudo systemctl restart lighthouse-vn

Here the service names we've used are lighhtouse-bn and lighthouse-vc, in Somer Esat's guide he has used lighthousebeacon and lighthousevalidator. Change these names in the above command to suit your service files. If you don't know the name, look for the names either via:

systemctl list-units

or by looking for .service files in the output of:

ls /etc/system/systemd/

At this point, you have updated your nodes and we are ready to check they are running and can clean up any left over files.

To check the node's status:

systemctl status lighthouse-bn

and 

systemctl status lighthouse-vc

again replacing the names with your service file names.

The service should report active (running) if everything is fine and provide some output logs.

Finally, remove the leftover file we downloaded earlier. NOTE: The following command removes all files starting with lighthouse, so make sure the lighthouse-<VERSION>-<BINARY_TYPE>.tar.gz file is the only one in the current directory starting with lighthouse- before running the following command.

rm lighthouse-**

That's it. Lighthouse is now running the latest version. Congrats!

Docker Upgrade Guide

The latest Lighthouse release is pushed automatically to dockerhub. This means the latest version of Lighthouse can be updated by pulling the latest image.

This can be done via:

docker pull sigp/lighthouse

Once the new version is downloaded, the docker containers can be restarted.

The containers can be named and constructed specifically for each set up. You can list your running containers via:

docker ps

An example result could look like:

CONTAINER ID   IMAGE                       COMMAND                  CREATED       STATUS       PORTS                                                                                          NAMES
aaf037b27601   sigp/lighthouse:v2.0.1      "sh /setup/start-bea…"   4 hours ago   Up 4 hours   0.0.0.0:9001->9001/tcp, 0.0.0.0:9001->9001/udp, :::9001->9001/tcp, :::9001->9001/udp           lighthouse_bn
bbf03db27601   sigp/lighthouse:v2.0.1      "sh /setup/start-val…"   4 hours ago   Up 4 hours                                                                                                  lighthouse_vc

The containers need to be shutdown, removed and re-created. If you are using a docker-compose file, this can be done via

docker-compose down
docker-compose up --build -d

If you are not using docker-compose you need to manually stop and remove the docker containers via

docker stop lighthouse_bn && docker rm lighthouse_bn
docker stop lighthouse_vc && docker rm lighthouse_vc

You then need to start them again using the same commands you originally created them with (dependent on your set up).

After the restart the docker containers should be running the latest version of Lighthouse. Congrats!

Binary Upgrade Guide

If you are running Lighthouse straight from a binary, the upgrade path is similar to that of the systemd upgrade.

The first step is to download the latest version of the Lighthouse client. The releases are built for a number of architectures as explained in the pre-built binaries section of the Lighthouse book.

For this example, we are going to use the x86_64-unknown-linux-gnu (most desktops/laptops) binary and the version 2.0.1 of Lighthouse. (You can check the latest version of Lighthouse on the github repository, or use the automatic download script provided below).

To download the binary, replace version number and binary type you wish to download (in the first two lines respectively) and run:

export LH_VERSION=v2.0.1
export LH_BINARY_TYPE=x86_64-unknown-linux-gnu
curl -LO https://github.com/sigp/lighthouse/releases/download/$LH_VERSION/lighthouse-$LH_VERSION-$LH_BINARY_TYPE.tar.gz
curl -LO https://github.com/sigp/lighthouse/releases/download/$LH_VERSION/lighthouse-$LH_VERSION-$LH_BINARY_TYPE.tar.gz.asc
tar xvf lighthouse-$LH_VERSION-$LH_BINARY_TYPE.tar.gz

or you can download the latest version (replacing the binary type with the following):

export LH_BINARY_TYPE=x86_64-unknown-linux-gnu
export LH_VERSION=$(curl --silent "https://api.github.com/repos/sigp/lighthouse/releases/latest" |grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/')
curl -LO https://github.com/sigp/lighthouse/releases/download/$LH_VERSION/lighthouse-$LH_VERSION-$LH_BINARY_TYPE.tar.gz
curl -LO https://github.com/sigp/lighthouse/releases/download/$LH_VERSION/lighthouse-$LH_VERSION-$LH_BINARY_TYPE.tar.gz.asc
tar xvf lighthouse-$LH_VERSION-$LH_BINARY_TYPE.tar.gz

At this point, you should verify the signature of the downloaded data to ensure it was built by Sigma Prime.

You should now have a lighthouse binary in your current working directory.

To check its version and build-type run:

./lighthouse --version

Which will output the version in the following format:

Lighthouse v2.0.1-fff01b2
BLS library: blst-modern
SHA256 hardware acceleration: true
Specs: mainnet (true), minimal (false)

We now need to install the correct and verified binary to the system. This can done via:

sudo cp lighthouse /usr/bin

You should now shutdown your current running instance(s) of Lighthouse and create a new one with the same command line parameters you used in your initial instance.

Once restarted, you should now be running the new version of Lighthouse. Congrats!

Verify Binary Signatures

When downloading our release binaries from github, we recommend verifying the signature that is published alongside the binary. This check ensures that the data you have downloaded is certified by Sigma Prime, ensuring you are running the official version of Lighthouse.

To verify the signature, we first assume the steps of downloading the zipped binary and the signature has been completed such that:

ls

shows the lighthouse-<VERSION>-<BINARY_TYPE>.tar.gz and lighthouse-<VERSION>-<BINARY_TYPE>.tar.gz.asc files.

We next need to make sure our version of the Sigma Prime PGP key is up to date. This requires the gpg utility (you may need to download this if not already installed).

To refresh the Sigma Prime PGP key run the following:

gpg --recv-key 15E66D941F697E28F49381F426416DC3F30674B0

Now to verify the signature, run:

gpg --verify lighthouse-$LH_VERSION-$LH_BINARY_TYPE.tar.gz.asc

If the result returns Good Signature then you can be sure the Lighthouse binary you have downloaded is the official one without data corruption.

The result may display 

WARNING: This key is not certified with a trusted signature!
         There is no indication that the signature belongs to the owner.
Primary key fingerprint: 15E6 6D94 1F69 7E28 F493  81F4 2641 6DC3 F306 74B0

This is an expected result, which just says that you don't specifically trust the Sigma Prime public key.